home *** CD-ROM | disk | FTP | other *** search
/ PC World 2000 February / PCWorld_2000-02_cd.bin / Software / Servis / FFE / MOD.SWG / 0054_PSM Module.pas < prev    next >
Pascal/Delphi Source File  |  1997-05-11  |  19KB  |  377 lines
  1.            Protracker Studio Module Format Specification v1.00
  2.  
  3. As mentioned in the last document, another format would be provided if the
  4. Protracker Studio 16 format weren't flexible enough.  Well, here it is.
  5. Sorry if I have inconvenienced anyone, but this format allows me to port
  6. in most any kind of music file.  I've currently ported the following formats
  7. to the PSM format:  MODs, WOWs, Oktalizer, Scream Tracker 2.x, Scream Tracker
  8. 3.x, and Composer 669.
  9.  
  10. Below lists the format of the Protracker Studio Module (PSM) header.
  11.  
  12. ╒═════════════════════════════════════════════════════════════════════════════╕
  13. │ PSM Header Format:                                                          │
  14. ╘═════════════════════════════════════════════════════════════════════════════╛
  15. │Length        │Description
  16. ┼─────────┬────┼───────────────────────────────────────────────────────────────
  17. │4 Bytes  │   0├─ Sig ─
  18. │         │    │  The signature for the file.  This should ALWAYS be set to
  19. │         │    │    PSM■ to act as the signature but also part of the string
  20. │         │    │    when TYPEing the PSM file to the screen.
  21. │60 Bytes │   4├─ Song Name ─
  22. │         │    │  This contains the 59-character name of the music file.  it
  23. │         │    │    may contain the name of the MOD if converted from a MOD, or
  24. │         │    │    it may contain information on number of channels, etc.
  25. │         │    │    The final byte, 60, MUST have a ^Z in it.
  26. │1 Byte   │  64├─ Song Type ─
  27. │         │    │  7 6 5 4 3 2 1 0
  28. │         │    │  │ │ │ │ │ │ │ └─ 0 - Module (w/samp.), 1 - Song (w/o samples)
  29. │         │    │  │ │ │ │ │ │ └─── 0 - 3 octave Protracker, 1 - 5 octave
  30. │         │    │  │ │ │ │ │ └───── Reserved
  31. │         │    │  │ │ │ │ └─────── Reserved
  32. │         │    │  │ │ │ └───────── Reserved
  33. │         │    │  │ │ └─────────── Reserved
  34. │         │    │  │ └───────────── Reserved
  35. │         │    │  └─────────────── Reserved
  36. │1 Byte   │  65├─ Song Version ─
  37. │         │    │  For this version of the PSM format, this will ALWAYS contain
  38. │         │    │    a $10, thus the version is 1.00.
  39. │1 Byte   │  66├─ Pattern Version ─
  40. │         │    │  This field can contain a 0 or a 1.  The 0 means the patterns
  41. │         │    │    stored in the module are in the 32 channel file format.  A
  42. │         │    │    version 1 signifies the patterns as being stored as a 255
  43. │         │    │    channel format.
  44. │1 Byte   │  67├─ Default Speed ─
  45. │         │    │  This is the default "click" speed for the music file.  Thus,
  46. │         │    │    for every countdown to zero from this value, the next
  47. │         │    │    pattern line will be processed.
  48. │1 Byte   │  68├─ Default BPM ─
  49. │         │    │  This is the default Amiga BPM value.  It is calculated as
  50. │         │    │    described below.  The only reason that the Amiga BPM format
  51. │         │    │    is still followed is that it allows more control over the
  52. │         │    │    final hz value.  Range: 32 to 255.
  53. │1 Byte   │  69├─ Master Volume ─
  54. │         │    │  The Master Volume value for the module.  This can range from
  55. │         │    │    0 (0%) to 255 (100%).
  56. │1 Word   │  70├─ Song Length ─
  57. │         │    │  This value contains the number of orders to play for this
  58. │         │    │    song.
  59. │         │    │  Contrary to the size of this value, the song length can only
  60. │         │    │    range from 1 to 255.  This value was made a Word to
  61. │         │    │    simplify coding, but it can also be used for expandability
  62. │         │    │    in the future.
  63. │1 Word   │  72├─ Number of Orders ─
  64. │         │    │  This is the number of orders that is stored at the Orders
  65. │         │    │    Offset.  Orders are the same thing as sequences, and they
  66. │         │    │    represent the order of the patterns to play.  This value
  67. │         │    │    is currently limited to the range of 1 to 255.
  68. │1 Word   │  74├─ Number of Patterns ─
  69. │         │    │  This field describes the number of patterns in this module.
  70. │         │    │    There can currently only be 1 to 255 patterns.
  71. │1 Word   │  76├─ Number of Samples ─
  72. │         │    │  This field describes the number of samples and sample
  73. │         │    │    structures stored in this module.  This is limited from
  74. │         │    │    1 to 255.
  75. │1 Word   │  78├─ Number of Channels to Play ─
  76. │         │    │  This field describes the maximum number of channels in this
  77. │         │    │    module to PLAY.  This is currently limited to a range of 1
  78. │         │    │    to 32.  This differs from the Number of Channels to Process
  79. │         │    │    field.  The Number of Channels to Process (NCP) describes
  80. │         │    │    the MAXIMUM number of channels to process.  As an example,
  81. │         │    │    when converting 669 files, I set the NCP to 9 because I
  82. │         │    │    put some track information on Channel 8, but the Number
  83. │         │    │    of Channels to Play was set to 8, and the channel numbers
  84. │         │    │    to play were from 0 to 7.
  85. │1 Word   │  80├─ Number of Channels to Process ─
  86. │         │    │  See Above.
  87. │1 Long   │  82├─ Offset of the Orders ─
  88. │         │    │  Offset FROM the start of the header of the orders.
  89. │1 Long   │  86├─ Offset of the Initial Pan Positions ─
  90. │         │    │  Offset FROM the start of the header of the pan positions.
  91. │1 Long   │  90├─ Offset of the Patterns ─
  92. │         │    │  Offset FROM the start of the header of the patterns.
  93. │1 Long   │  94├─ Offset of the Sample Headers ─
  94. │         │    │  Offset FROM the start of the header of the sample headers.
  95. │1 Long   │  98├─ Offset of the Comments ─
  96. │         │    │  Offset FROM the start of the header of the comments.
  97. │1 Long   │ 102├─ Total Pattern Size ─
  98. │         │    │  This is the total size of the patterns to be loaded from the
  99. │         │    │    PatternsOfs location.  The reason it is stored here is
  100. │         │    │    because there is no easy way to determine the size of all
  101. │         │    │    of the patterns.
  102. │10 Longs │ 106├─ Fillers ─
  103. │         │    │  These are fillers that can be used for future expansion.
  104. │         │    │    These are FILE OFFSETS of additional structures.
  105. ┴─────────┼────┴──────────────┬────────────────────────────────────────────────
  106.           │ 146 Bytes long    │
  107.           └───────────────────┘
  108. Apologies for the last format.  This format header will NEVER change.  I
  109. figure the 10 Filler offsets should give sufficient expansion room.
  110.  
  111.  
  112. ╒══════════════════════════════════════════════════════════════════════════════╕
  113. │ PSM BPM:                                                                     │
  114. ╘══════════════════════════════════════════════════════════════════════════════╛
  115. Beats Per Minute can be centered around the following equations:
  116.  
  117.         Convert_Hz_To_BPM:  Hz*2/5   or   Hz/2.5
  118.         Convert_BPM_To_Hz:  BPM*5/2  or   BPM*2.5
  119.  
  120. Why use BPM instead of Hz?  Let's do some calculations.  BPM can only range
  121. from 32 to 255 in the format that we are dealing with.  This gives us a
  122. Hz range from 12.8hz to 102hz.  There are a lot of fractional parts in the
  123. hertz rates described by BPM.  However, if we only use a hertz value, we can
  124. only reasonably store a 13hz instead of a 12.8hz.
  125.  
  126. Thus, here are some typical hz/BPM rates:
  127.  
  128.                 MOD:    125 BPM, 50 hz
  129.                 669:     80 BPM, 32 hz
  130.  
  131.  
  132. ╒══════════════════════════════════════════════════════════════════════════════╕
  133. │ PSM Orders Format:                                                           │
  134. ╘══════════════════════════════════════════════════════════════════════════════╛
  135. The Header variable Offset to Orders points to this section.
  136.  
  137. Although yet undetermined precisely, the Orders in PSM have an interactive
  138. nature about them.  Through the use of a mini-"programming" language, all
  139. sorts of effects and special cases with the orders can be made.  By doing
  140. this, the creator could turn off certain tracks at a certain time while
  141. looping a specified set of orders.  Or, a section of orders could loop
  142. until a flag was set by the programmer of a game... many possibilities
  143. exist.
  144.  
  145. Orders are stored in the order that they will play in.  As an example:
  146.  
  147. 01 04 05 31
  148.  
  149. The Number of Orders field in the header will contain a 4 to signify 4
  150. orders, in this instance.
  151.  
  152. Immediately following these orders is a word containing the size of the
  153. additional Orders "language."  For the time being, this will only contain
  154. a zero.
  155.  
  156.  
  157. ╒══════════════════════════════════════════════════════════════════════════════╕
  158. │ PSM Version 0 Pattern Format (32 Channel Version)                            │
  159. ╘══════════════════════════════════════════════════════════════════════════════╛
  160. The Header variable Offset of Patterns points here.
  161.  
  162. PSM tracks contain all information pertinent to the note, instrument, volume,
  163. special effects, and the special effect data.  A single PSM's track size
  164. can range from 2 bytes or larger (typically, 6 bytes is the largest).
  165.  
  166. All tracks belonging to a single row are stored one after another.  The
  167. row will be terminated with a zero.  This means that if channels 1, 4,
  168. and 7 are modified on the current row, they will be stored as such:
  169.  
  170.                 Channel 1...Channel 4...Channel 7...0
  171.  
  172. The description of the format of a single PSM track is as follows.  The
  173. command byte is first:
  174.  
  175.   Command Byte:         Where:     a - Is there a note or instrument change?
  176.         abcddddd                   b - Is there a volume change?
  177.                                    c - Is there a special effect change?
  178.                                ddddd - The channel number for this info
  179.                                        ranging from 0 to 31.
  180.  
  181. If the command byte is zero then the end of the current row is encountered.
  182.  
  183. The process for parsing the command information is like so:
  184.  
  185.         1) Load the command byte.
  186.         2) Is it a zero?  If so, we're at the end of the row.
  187.         3) Channel = Command and 31.
  188.         4) Set up channel pointers.
  189.         5) If Command and 80h > 0 then Grab Note Information.
  190.         6) If Command and 40h > 0 then Grab Volume Information.
  191.         7) If Command and 20h > 0 then Grab Special Effect Information.
  192.  
  193. Grab Note Information:
  194. ──────────────────────
  195.         1) Load in the next byte.  This byte is the note.
  196.            ╔═════════╤═════════╤═════════╤═════════╤═════════╗
  197.            ║ C-0   0 │ C-1  12 │ C-2  24 │ C-3  36 │ C-4  48 ║
  198.            ║ C#0   1 │ C#1  13 │ C#2  25 │ C#3  37 │ C#4  49 ║
  199.            ║ D-0   2 │ D-1  14 │ D-2  26 │ D-3  38 │ D-4  50 ║
  200.            ║ D#0   3 │ D#1  15 │ D#2  27 │ D#3  39 │ D#4  51 ║
  201.            ║ E-0   4 │ E-1  16 │ E-2  28 │ E-3  40 │ E-4  52 ║
  202.            ║ F-0   5 │ F-1  17 │ F-2  29 │ F-3  41 │ F-4  53 ║
  203.            ║ F#0   6 │ F#1  18 │ F#2  30 │ F#3  42 │ F#4  54 ║
  204.            ║ G-0   7 │ G-1  19 │ G-2  31 │ G-3  43 │ G-4  55 ║
  205.            ║ G#0   8 │ G#1  20 │ G#2  32 │ G#3  44 │ G#4  56 ║
  206.            ║ A-0   9 │ A-1  21 │ A-2  33 │ A-3  45 │ A-4  57 ║
  207.            ║ A#0  10 │ A#1  22 │ A#2  34 │ A#3  46 │ A#4  58 ║
  208.            ║ B-0  11 │ B-1  23 │ B-2  35 │ B-3  47 │ B-4  59 ║
  209.            ╚═════════╧═════════╧═════════╧═════════╧═════════╝
  210.         2) Load in the next byte.  This is the instrument number.
  211.  
  212.  
  213. Grab Volume Information:
  214. ────────────────────────
  215.         1) Load in the next byte.  This byte is the volume, range 0 to 64.
  216.  
  217. Grab Special Effects Information:
  218. ─────────────────────────────────
  219.         1) Load in the next byte.  This byte is the special effect, range 0 to
  220.            255.
  221.         2) The next byte(s) are dependant on which special effect command
  222.            is being used.  Load in the appropriate number of bytes, based
  223.            on what the effect needs.
  224.  
  225.         Refer to the file EFX.DOC.
  226.  
  227.  
  228. The pattern data follows this header located at the beginning of each pattern:
  229.  
  230.         Byte    Name            Description
  231.        ──────  ─────────────── ────────────────────────────────────────
  232.          0-1   Size     (Word) Size is the total size of the ENTIRE
  233.                                 pattern, INCLUDING bytes 0 through 3.
  234.                                 This number is paragraph aligned.  This
  235.                                 means that if a pattern is 253 bytes
  236.                                 long, its actual size is 257.
  237.            2   NumLines (Byte) This is the number of pattern lines in
  238.                                 the pattern.  If a pattern only uses
  239.                                 30 lines and the pattern must terminate
  240.                                 to the next pattern at this point,
  241.                                 store a 30 here.  Otherwise, ALWAYS store
  242.                                 a 64 so the entire pattern will play.
  243.            3   NumChans (Byte) This is the number of channels that this
  244.                                 pattern uses.
  245.         4-??   Track           This is Track 1, terminated with a -1.
  246.                                 The other tracks follow immediately after
  247.                                 this.
  248.  
  249.  
  250. ╒══════════════════════════════════════════════════════════════════════════════╕
  251. │ PSM Sample Header Format:                                                    │
  252. ╘══════════════════════════════════════════════════════════════════════════════╛
  253. The Header variable Offset of Sample Headers points here.
  254.  
  255. All of the headers follow each other for Number of Samples Headers.
  256.  
  257. │Length        │Description
  258. ┼─────────┬────┼─────────────────────────────────────────────────────────────
  259. │13 Bytes │   0├─ Sample Filename ─
  260. │         │    │  This is the filename for the sample.  Byte 13 contains a 0.
  261. │24 Bytes │  13├─ Sample Description ─
  262. │         │    │  This is the description of the sample.
  263. │1 Long   │  37├─ File Offset ─
  264. │         │    │  This is the offset of the raw sample data from the start of
  265. │         │    │    the header.
  266. │1 Long   │  41├─ Memory Location ─
  267. │         │    │  This is the physical offset in RAM/DRAM of the sample.
  268. │1 Word   │  45├─ Sample Number ─
  269. │         │    │  The physical number of the sample is stored here.  Range:
  270. │         │    │    1 - 255.
  271. │1 Byte   │  47├─ Sample Type ─
  272. │         │    │  This byte contains the bits that may be set describing the
  273. │         │    │    sample.
  274. │         │    │
  275. │         │    │   7 6 5 4 3 2 1 0
  276. │         │    │   │ │ │ │ │ │ │ └─ 0 - Digital, 1 - Synthesized
  277. │         │    │   │ │ │ │ │ │ └─── Reserved
  278. │         │    │   │ │ │ │ │ └───── 0 - 8-bit, 1 - 16-bit
  279. │         │    │   │ │ │ │ └─────── 0 - Signed, 1 - Unsigned
  280. │         │    │   │ │ │ └───────── 0 - Deltas, 1 - Raw
  281. │         │    │   │ │ └─────────── 0 - Loop normally, 1 - Bidirectional
  282. │         │    │   │ └───────────── 1 - Gravis patch (unsupported)
  283. │         │    │   └─────────────── 0 - No loop, 1 - Loop sample
  284. │         │    │
  285. │1 Long   │  48├─ Sample Length ─
  286. │         │    │  This contains the length of the sample.  Range:
  287. │         │    │    0 to 1,048,575.
  288. │1 Long   │  52├─ Sample Repeat Start ─
  289. │         │    │  This contains the start of the repeat for the sample.  Range:
  290. │         │    │    0 to Sample Length.
  291. │1 Long   │  56├─ Sample Repeat End ─
  292. │         │    │  This contains the end of the repeat for the sample.  Range:
  293. │         │    │    Sample Repeat Start to Sample Length.  If this value is
  294. │         │    │    less than the Sample Repeat Start, then the sample will
  295. │         │    │    loop backwards.  If there is to be NO LOOP, set this to
  296. │         │    │    -1.
  297. │1 Byte   │  60├─ Fine Tune ─
  298. │         │    │  This contains the Fine Tune for the sample.  Range: 0-15.
  299. │         │    │    0 - Tuning 0                8 - Tuning -8
  300. │         │    │    1 - Tuning 1                9 - Tuning -7
  301. │         │    │    2 - Tuning 2                10 - Tuning -6
  302. │         │    │    3 - Tuning 3                11 - Tuning -5
  303. │         │    │    4 - Tuning 4                12 - Tuning -4
  304. │         │    │    5 - Tuning 5                13 - Tuning -3
  305. │         │    │    6 - Tuning 6                14 - Tuning -2
  306. │         │    │    7 - Tuning 7                15 - Tuning -1
  307. │1 Byte   │  61├─ Volume ─
  308. │         │    │  The default volume of the sample.  Range: 0 to 64.
  309. │1 Word   │  62├─ C Octave 2 Frequency ─
  310. │         │    │  This is the frequency for the sample at a C of Octave 2.
  311. │         │    │  Typical values are 8,000 hz to 8,448 hz.
  312. ┴─────────┼────┴───────────┬──────────────────────────────────────────────────
  313.           │  64 bytes long │
  314.           └────────────────┘
  315.  
  316.  
  317. ╒══════════════════════════════════════════════════════════════════════════════╕
  318. │ PSM Sample Format:                                                           │
  319. ╘══════════════════════════════════════════════════════════════════════════════╛
  320. Only the digital sample format has been defined thus far.  In order to appeal
  321. to archivers more, the sample storage format has changed.  Instead of being
  322. stored as raw data as in all trackers I am aware of, the format was changed
  323. to use "deltas."  The algorithm for converting a sample to deltas is:
  324.  
  325.                 Get the number of sample bytes to process.
  326.                   Call this SamplesLeft.
  327.  
  328.                 Set Delta counter to 0.
  329.  
  330.                 DO
  331.                   Get a byte from the buffer.
  332.                   Store the byte in Temp.
  333.                   Subtract the Delta counter from the byte.
  334.                   Store it in the buffer.
  335.                   Move the Temp byte into the Delta Counter
  336.                   Decrement SamplesLeft.
  337.                 WHILE(SamplesLeft <> 0)
  338.  
  339. The technique for conversion back to the raw data is:
  340.  
  341.                 Get the number of sample bytes to process.
  342.                   Call this SamplesLeft.
  343.  
  344.                 Set Delta counter to 0.
  345.  
  346.                 DO
  347.                   Get a byte from the buffer.
  348.                   Add onto the byte the Delta Counter.
  349.                   Store the byte in Delta Counter.
  350.                   Store the byte in Temp.
  351.                   Decrement SamplesLeft.
  352.                 WHILE(SamplesLeft <> 0)
  353.  
  354. Advantages of using deltas:
  355.  
  356. Take this raw sample data that I copied directly out of a sample:
  357.  
  358. RAW:    64  66  67  68  69  70  71  73  75  77  76
  359. DELTAS: 64   2   1   1   1   1   1   2   2   2  -1
  360.  
  361. These particular deltas will compress MUCH better in any archiver.
  362.  
  363.  
  364. ╒══════════════════════════════════════════════════════════════════════════════╕
  365. │ PSM Comment Format, Version 0:                                               │
  366. ╘══════════════════════════════════════════════════════════════════════════════╛
  367. This format resembles an ILBM format.  Only one thing is currently defined
  368. in this format.
  369.  
  370.         Signature     Description
  371.         ─────────     ─────────────────────────────────────────────────
  372.           TEXT        Immediately following this four character
  373.                         identifier is a WORD describing the length
  374.                         of the upcoming text.
  375.  
  376.  
  377.